<h2>DESCRIPTION</h2>

<em>r.what</em> outputs the category values and (optionally) the category
labels associated with user-specified locations on raster input map(s).
Locations are specified as geographic x,y coordinate pairs (i.e., pair of
eastings and northings); the user can also (optionally) associate a label
with each location.

<p>The input coordinates can be entered directly on the command line
via <b>coordinates</b> parameter, or redirected via <tt>stdin</tt>
from an input text file, script, or piped from another program
(like <em><a href="v.out.ascii.html">v.out.ascii</a></em>). Coordinates
can be given also as a vector points map (<b>points</b>).

<p>If none of the above input methods are used and the module is run from the
terminal prompt, the program will interactively query the user for point
locations and labels.
<p>Each line of the input consists of an easting, a northing, and an optional
label, which are separated by spaces. In interactive mode, the word
"<tt>end</tt>" must be typed after the last pair of input coordinates.
<p><em>r.what</em> output consists of the input geographic location and label,
and, for each user-named raster map layer, the category value, and (if
the <b>-f</b> label flag is specified) the category label associated with
the cell(s) at this geographic location.


<h2>EXAMPLES</h2>

<h3>Input coordinates given as an option</h3>

The module's <b>coordinates</b> parameter can be used to enter coordinate
pairs directly. The maximum number of pairs will be limited by your system's
maximum input line length (e.g. 4096 characters).

<div class="code"><pre>
g.region raster=landuse96_28m,aspect -p
r.what map=landuse96_28m,aspect coordinates=633614.08,224125.12,632972.36,225382.87 -f

633614.08|224125.12||2|Low Intensity Developed|209.5939|209 degrees ccw from east
632972.36|225382.87||15|Southern Yellow Pine|140.7571|140 degrees ccw from east
</pre></div>

<h3>Input coordinates given as a vector points map</h3>

Coordinates can be read from existing vector points map by
specifying <b>points</b> option. Other features than points or
centroids are ignored. Example: query North Carolina county number for
each community college:

<div class="code"><pre>
g.region raster=boundary_county_500m -p
r.what map=boundary_county_500m points=comm_colleges

145096.859150|154534.264884||39
616341.437150|146049.750884||51
...
</pre></div>

<h3>Input coordinates given as a vector points map with cats</h3>

Coordinates can be read from existing vector points map by
specifying <b>points</b> option. Other features than points or
centroids are ignored. Using the <b>v</b> flag you can get also
the cat for each feature. Example: query North Carolina county
number for each community college:

<div class="code"><pre>
g.region raster=boundary_county_500m -p
r.what map=boundary_county_500m points=comm_colleges -v

1|145096.859150|154534.264884||39
2|616341.437150|146049.750884||51
...
</pre></div>


<h3>Input coordinates given as a vector points map, output into CSV file</h3>

Coordinates can be read from existing vector points map by
specifying <b>points</b> option. Other features than points or
centroids are ignored. The output is stored in a CSV file including header
row. Example: query North Carolina county number for each community college:

<div class="code"><pre>
g.region raster=boundary_county_500m -p
r.what map=boundary_county_500m points=comm_colleges \
       separator=comma output=result.csv -n
       
cat result.csv 
easting,northing,site_name,boundary_county_500m
145096.859150,154534.264884,,39
616341.437150,146049.750884,,51
410595.719150,174301.828884,,71
...
</pre></div>

<h3>Input from a text file containing coordinates</h3>

The contents of an ASCII text file can be redirected to <em>r.what</em>
as follows. If we have a file called <i>input_coord.txt</i> containing the
whitespace separated coordinates and optionally labels, the resulting 
raster map values are extracted:

<div class="code"><pre>
cat input_coord.txt 
633614.08 224125.12 site 1
632972.36 225382.87 site 2

r.what map=landuse96_28m,aspect &lt; input_coord.txt

633614.08|224125.12|site 1|2|209.5939
632972.36|225382.87|site 2|15|140.7571
</pre></div>

<h3>Input from standard input on the command line</h3>

Input coordinates may be given directly from standard input (<tt>stdin</tt>),
for example (input data appears between the "<tt>EOF</tt>" markers):

<div class="code"><pre>
r.what map=landuse96_28m,aspect &lt;&lt; EOF
633614.08 224125.12 site 1
632972.36 225382.87 site 2
EOF

633614.08|224125.12|site 1|2|209.5939
632972.36|225382.87|site 2|15|140.7571
</pre></div>

<div class="code"><pre>
echo "633614.08 224125.12" | r.what map=landuse96_28m,aspect

633614.08|224125.12||2|209.5939
</pre></div>

<h3>Input coordinates piped from another program</h3>

The input coordinates may be "piped" from the standard output
(<tt>stdout</tt>) of another program. In the next example, vector
point coordinates are piped from the
<em><a href="v.out.ascii.html">v.out.ascii</a></em> module. 

<div class="code"><pre>
v.out.ascii comm_colleges separator=space | r.what map=boundary_county_500m

145096.8591495|154534.26488388|1|39
616341.4371495|146049.75088388|2|51
410595.7191495|174301.82888388|3|71
...
</pre></div>

<h3>Output containing raster map category labels</h3>

Here we use the <b>-f</b> label flag to enable the output of category labels
associated with the raster cell(s), as well as values (categorical maps only).

<div class="code"><pre>
r.what -f map=landuse96_28m,aspect &lt;&lt; EOF
633614.08 224125.12 site 1
632972.36 225382.87 site 2
EOF

633614.08|224125.12|site 1|2|Low Intensity Developed|209.5939|209 degrees ccw from east
632972.36|225382.87|site 2|15|Southern Yellow Pine|140.7571|140 degrees ccw from east
</pre></div>

<h2>NOTE</h2>

The maximum number of raster map layers that can be queried at one time is 400.
<!-- as given by raster/r.what/main.c "#define NFILES 400" -->

<h2>TODO</h2>

<ul>
  <li>Fix <b>400 maps</b> limit</li>
</ul>

<h2>SEE ALSO</h2>

<em>
<a href="r.category.html">r.category</a>,
<a href="r.report.html">r.report</a>,
<a href="r.stats.html">r.stats</a>,
<a href="r.series.html">r.series</a>,
<a href="r.univar.html">r.univar</a>,
<a href="v.what.html">v.what</a>,
<a href="v.what.rast.html">v.what.rast</a>,
<a href="v.what.vect.html">v.what.vect</a>
</em>

<h2>AUTHOR</h2>
Michael Shapiro, U.S. Army Construction Engineering Research Laboratory<br>
Vector point input added by Martin Landa, Czech Technical University in Prague, Czech Republic

<!--
<p>
<i>Last changed: $Date$</i>
-->
